home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / gethostbyname.man < prev    next >
Encoding:
Text File  |  1989-03-15  |  6.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4. GETHOSTBYNAME         C Library Procedures          GETHOSTBYNAME
  5.  
  6.  
  7.  
  8. NNAAMMEE
  9.      gethostbyname, gethostbyaddr, gethostent, sethostent,
  10.      endhostent, herror - get network host entry
  11.  
  12. SSYYNNOOPPSSIISS
  13.      ##iinncclluuddee <<nneettddbb..hh>>
  14.  
  15.      eexxtteerrnn iinntt hh__eerrrrnnoo;;
  16.  
  17.      ssttrruucctt hhoosstteenntt **ggeetthhoossttbbyynnaammee((nnaammee))
  18.      cchhaarr **nnaammee;;
  19.  
  20.      ssttrruucctt hhoosstteenntt **ggeetthhoossttbbyyaaddddrr((aaddddrr,, lleenn,, ttyyppee))
  21.      cchhaarr **aaddddrr;; iinntt lleenn,, ttyyppee;;
  22.  
  23.      ssttrruucctt hhoosstteenntt **ggeetthhoosstteenntt(())
  24.  
  25.      sseetthhoosstteenntt((ssttaayyooppeenn))
  26.      iinntt ssttaayyooppeenn;;
  27.  
  28.      eennddhhoosstteenntt(())
  29.  
  30.      hheerrrroorr((ssttrriinngg))
  31.      cchhaarr **ssttrriinngg;;
  32.  
  33. DDEESSCCRRIIPPTTIIOONN
  34.      _G_e_t_h_o_s_t_b_y_n_a_m_e and _g_e_t_h_o_s_t_b_y_a_d_d_r each return a pointer to an
  35.      object with the following structure describing an internet
  36.      host referenced by name or by address, respectively.  This
  37.      structure contains either the information obtained from the
  38.      name server, _n_a_m_e_d(8), or broken-out fields from a line in
  39.      /_e_t_c/_h_o_s_t_s.  If the local name server is not running these
  40.      routines do a lookup in /_e_t_c/_h_o_s_t_s.
  41.  
  42.           struct    hostent {
  43.                char *h_name;  /* official name of host */
  44.                char **h_aliases;   /* alias list */
  45.                int  h_addrtype;    /* host address type */
  46.                int  h_length; /* length of address */
  47.                char **h_addr_list; /* list of addresses from name server */
  48.           };
  49.           #define   h_addr  h_addr_list[0]   /* address, for backward compatibility */
  50.  
  51.      The members of this structure are:
  52.  
  53.      h_name       Official name of the host.
  54.  
  55.      h_aliases    A zero terminated array of alternate names  for
  56.                   the host.
  57.  
  58.      h_addrtype   The type of address being  returned;  currently
  59.                   always AF_INET.
  60.  
  61.  
  62.  
  63. Sprite v1.0               April 5, 1988                         1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GETHOSTBYNAME         C Library Procedures          GETHOSTBYNAME
  71.  
  72.  
  73.  
  74.      h_length     The length, in bytes, of the address.
  75.  
  76.      h_addr_list  A zero terminated array  of  network  addresses
  77.                   for  the  host.  Host addresses are returned in
  78.                   network byte order.
  79.  
  80.      h_addr       The first address in h_addr_list; this  is  for
  81.                   backward compatiblity.
  82.  
  83.      When using the nameserver, _g_e_t_h_o_s_t_b_y_n_a_m_e will search for the
  84.      named  host in the current domain and its parents unless the
  85.      name ends in a dot.  If the name contains no dot, and if the
  86.      environment  variable  ``HOSTALAIASES'' contains the name of
  87.      an alias file, the alias file will first be searched for  an
  88.      alias  matching  the  input  name.   See _h_o_s_t_n_a_m_e(7) for the
  89.      domain search procedure and the alias file format.
  90.  
  91.      _S_e_t_h_o_s_t_e_n_t may be used to request the use of a connected TCP
  92.      socket  for queries.  If the _s_t_a_y_o_p_e_n flag is non-zero, this
  93.      sets the option to send all queries to the name server using
  94.      TCP and to retain the connection after each call to _g_e_t_h_o_s_t_-
  95.      _b_y_n_a_m_e or _g_e_t_h_o_s_t_b_y_a_d_d_r.  Otherwise, queries  are  performed
  96.      using UDP datagrams.
  97.  
  98.      _E_n_d_h_o_s_t_e_n_t closes the TCP connection.
  99.  
  100. DDIIAAGGNNOOSSTTIICCSS
  101.      Error return status from _g_e_t_h_o_s_t_b_y_n_a_m_e and _g_e_t_h_o_s_t_b_y_a_d_d_r  is
  102.      indicated by return of a null pointer.  The external integer
  103.      _h__e_r_r_n_o may then be checked to see whether this  is  a  tem-
  104.      porary  failure  or an invalid or unknown host.  The routine
  105.      _h_e_r_r_o_r can be used to print an error message describing  the
  106.      failure.  If its argument _s_t_r_i_n_g is non-NULL, it is printed,
  107.      followed by a colon and  a  space.   The  error  message  is
  108.      printed with a trailing newline.
  109.  
  110.      _h__e_r_r_n_o can have the following values:
  111.  
  112.           HOST_NOT_FOUND  No such host is known.
  113.  
  114.           TRY_AGAIN       This is usually a temporary  error  and
  115.                           means  that  the  local  server did not
  116.                           receive a response from  an  authorita-
  117.                           tive  server.   A  retry  at some later
  118.                           time may succeed.
  119.  
  120.           NO_RECOVERY     Some  unexpected  server  failure   was
  121.                           encountered.  This is a non-recoverable
  122.                           error.
  123.  
  124.           NO_DATA         The requested name is  valid  but  does
  125.                           not  have  an IP address; this is not a
  126.  
  127.  
  128.  
  129. Sprite v1.0               April 5, 1988                         2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GETHOSTBYNAME         C Library Procedures          GETHOSTBYNAME
  137.  
  138.  
  139.  
  140.                           temporary error. This  means  that  the
  141.                           name  is  known  to the name server but
  142.                           there is  no  address  associated  with
  143.                           this  name.  Another type of request to
  144.                           the name server using this domain  name
  145.                           will  result in an answer; for example,
  146.                           a mail-forwarder may be registered  for
  147.                           this domain.
  148.  
  149. FFIILLEESS
  150.      /etc/hosts
  151.  
  152. SSEEEE AALLSSOO
  153.      resolver(3), hosts(5), hostname(7), named(8)
  154.  
  155. CCAAVVEEAATT
  156.      _G_e_t_h_o_s_t_e_n_t is defined, and  _s_e_t_h_o_s_t_e_n_t  and  _e_n_d_h_o_s_t_e_n_t  are
  157.      redefined,  when  _l_i_b_c  is built to use only the routines to
  158.      lookup in /_e_t_c/_h_o_s_t_s and not the name server.
  159.  
  160.      _G_e_t_h_o_s_t_e_n_t reads the next line of  /_e_t_c/_h_o_s_t_s,  opening  the
  161.      file if necessary.
  162.  
  163.      _S_e_t_h_o_s_t_e_n_t is redefined to open and rewind the file.  If the
  164.      _s_t_a_y_o_p_e_n  argument is non-zero, the hosts data base will not
  165.      be closed after each call to _g_e_t_h_o_s_t_b_y_n_a_m_e or _g_e_t_h_o_s_t_b_y_a_d_d_r.
  166.      _E_n_d_h_o_s_t_e_n_t is redefined to close the file.
  167.  
  168. BBUUGGSS
  169.      All information is contained in a static area so it must  be
  170.      copied if it is to be saved.  Only the Internet address for-
  171.      mat is currently understood.
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0               April 5, 1988                         3
  196.  
  197.  
  198.  
  199.